isp-status System Model

Generated (UTC): 2026-02-18T16:27:13.597561Z

1. Overview

This document describes the internal operational model of isp-status.

It explains how probe data flows through the system, how decisions are made, how history is persisted, and how integrity is validated.

The goal is clarity of architecture.

2. Logical Flow Diagram

               ┌─────────────────────┐
               │  Probes (ping/http) │
               └──────────┬──────────┘
                          │
                   health.decide()
                          │
                     /api/status
                          │
                 SQLite minute writes
                          │
                  5m rollups (timer)
                          │
                     /api/history
                          │
                   Integrity checks
                          │
                     /api/health

3. Layer-by-Layer Explanation

3.1 Probes (ping/http)

Active network tests executed per uplink:

Interface operstate
Gateway ICMP (where applicable)
External ICMP targets
External HTTP checks

These provide raw signals only. They do not determine final state.

3.2 `health.decide()`

The decision engine.

Inputs: - Interface state - Gateway reachability - Successful ping counts - Successful HTTP counts

Output: - State code (0, 1, 2) - State reason (machine-readable)

This layer converts signals into usable operational truth.

3.3 `/api/status`

The real-time truth surface.

Responsibilities: - Executes probes - Applies decision engine - Persists minute state - Returns structured JSON

This endpoint is the canonical source of current state.

3.4 SQLite Minute Writes

Each state decision is persisted as a minute-resolution record.

This creates authoritative time-series history.

3.5 5-Minute Rollups (Timer)

A scheduled timer aggregates minute data into deterministic 5-minute buckets.

Why: - Stable chart widths - Reduced storage overhead - Structured availability reporting

3.6 `/api/history`

Provides structured historical truth:

5-minute aligned buckets
Daily summaries
Availability percentages
CSV export

This layer serves SLA analysis and reporting.

3.7 Integrity Checks

Independent evaluation of:

History freshness
Data gaps
SQLite health
Disk usage
Memory usage
Permissions
Timer behavior

This validates the monitoring engine itself.

3.8 `/api/health`

The monitoring-of-the-monitor.

Answers:

Is the engine functioning?
Are writes current?
Are gaps within tolerance?
Is the environment healthy?

This is separate from network state by design.

4. Separation of Concerns

The architecture intentionally separates:

Concern Endpoint

Network Usability /api/status Monitoring Integrity /api/health Historical Availability /api/history

This prevents conflating link failures with monitoring failures.

5. Design Principle

The system is built on:

Deterministic state evaluation
Explicit data persistence
Layered truth surfaces
Observable monitoring integrity

Dashboards are views. The API is truth.

6. Intended Outcome

This model ensures:

Troubleshooting begins with evidence
Historical availability is structured
Monitoring health is observable
Integrations are deterministic

The system is not just a dashboard. It's an operational instrument.